home *** CD-ROM | disk | FTP | other *** search
/ ETO Development Tools 2 / ETO Development Tools 2.iso / Tools - Objects / MacApp / MacApp CD Release / MacApp 2.0.1 (Many Libraries) / Interfaces / PInterfaces / UPatch.p < prev    next >
Encoding:
Text File  |  1990-10-25  |  5.1 KB  |  137 lines  |  [TEXT/MPS ]
  1. {[a-,body+,h-,o=100,r+,rec+,t=4,u+,#+,j=20/57/1$,n-]}
  2. { UPatch.p }
  3. { Copyright © 1985-1990 by Apple Computer, Inc.  All rights reserved. }
  4. {[f-]}
  5. {
  6.         T H E O R Y   O F    O P E R A T I O N
  7.  
  8. This unit implements a general trap-patching mechanism.  Two types of
  9. patches are implemented:
  10.  
  11. Normal Patch    The trap is patched such that it jumps to the routine
  12.             of your choice, ignoring the routine it previously
  13.             jumped to.    On a 128K ROM machine, the patch is made
  14.             by setting the trap address to your routine.  On a 64K
  15.             machine, a small block of code is allocated in the
  16.             system heap:  The trap address is set to point to the
  17.             block, and the block contains code to jump to your
  18.             routine.
  19.  
  20. Head Patch    The trap is patched such that it jumps to the
  21.             routine of your choice, then jumps to the trap's
  22.             routine.  Head patches come in two flavors:  with
  23.             no parameters and with one long-word parameter.  The
  24.             patch is made by allocating a small block of code in
  25.             the application heap (system heap for 64K ROMs).  The
  26.             trap address is set to the block, and the block contains
  27.             code to jump to your routine and return to the trap's
  28.             original address.
  29.  
  30. References to patches are kept in TrapPatch records.  For each trap
  31. patched you must define a variable of type TrapPatch.    This unit links
  32. the TrapPatch records to form a linked list for facilitate unpatching
  33. all patches without specifying each individual patch.
  34. }
  35. {[f+]}
  36.  
  37. {$IFC UNDEFINED UsingIncludes}
  38. {$SETC UsingIncludes := FALSE}
  39. {$ENDC}
  40.  
  41. {$IFC NOT UsingIncludes}
  42. UNIT UPatch;
  43.  
  44.     INTERFACE
  45.         {$ENDC}
  46.  
  47.         {$IFC UNDEFINED __UPatch__}
  48.         {$SETC __UPatch__ := FALSE}
  49.         {$ENDC}
  50.  
  51.         {$IFC NOT __UPatch__}
  52.         {$SETC __UPatch__ := TRUE}
  53.  
  54.         { • Auto-Include the requirements for this unit's interface. }
  55.         {$SETC UPatchIncludes := UsingIncludes}
  56.         {$SETC UsingIncludes := TRUE}
  57.         {$I+}
  58.         {$IFC UNDEFINED UsingTypes} {$I Types.p} {$ENDC}
  59.         {$IFC UNDEFINED UsingMemory} {$I Memory.p} {$ENDC}
  60.         {$SETC UsingIncludes := UPatchIncludes}
  61.  
  62.         TYPE
  63.             TrapPatchPtr        = ^TrapPatch;            { Preferred. The pointer type _MUST_ be
  64.                                                          declared first since the record is self
  65.                                                          referential }
  66.             TrapPatch            = RECORD
  67.                 jmpPtr:             Ptr;                { Addr of sys heap block }
  68.                 trapNum:            INTEGER;            { trap # being patched }
  69.                 oldTrapAddr:        LONGINT;            { old trap address }
  70.                 nextPatch:            TrapPatchPtr;        { next link in linked list of patches }
  71.                 END;
  72.  
  73.             CallBack             = RECORD
  74.                 saveRtnAdd:         INTEGER;            { Internal use }
  75.                 moveRefCon:         INTEGER;            { Internal use }
  76.                 refCon:             LONGINT;            { the refCon that will be passed as last
  77.                                                          parm }
  78.                 targOffset:         INTEGER;            { Internal use }
  79.                 jmpInst:            INTEGER;            { Internal use }
  80.                 jmpTarg:            LONGINT;            { Internal use }
  81.                 END;
  82.             CallBackPtr            = ^CallBack;
  83.  
  84.         { The following variable is really private but is in the interface just in case
  85.         you're doing something really wierd and you really need it }
  86.  
  87.         VAR
  88.             pPatchList:         TrapPatchPtr;            { Head of linked list of patches }
  89.  
  90.         PROCEDURE InitUPatch;
  91.         { Call this once to set things up. Initializes the linked list of patches to NIL. }
  92.  
  93.         PROCEDURE EachPatchDo(FUNCTION DoToPatch(thePatchPtr: TrapPatchPtr): BOOLEAN);
  94.         { Calls DoToPatch for each patch in the list from pPatchList to the last patch.
  95.         Stops at end of list or when DoToPatch returns TRUE.  DoToPatch may not remove patches. }
  96.  
  97.         FUNCTION HeadPatch(VAR thePatch: TrapPatch;
  98.                            theTrapNum: INTEGER;
  99.                            theRoutine: Ptr): INTEGER;
  100.         { HeadPatch patches a trap such that it calls theRoutine first, then executes the old trap
  101.         routine. theRoutine must be a procedure with no arguments. This type of patch is
  102.         implemented by setting up a block in the system heap, patching the trap to jump to the
  103.         block, and inserting code in the block that pushes the original trap address on the stack
  104.         and jumps to theRoutine. Thus, theRoutine returns to the original trap routine. }
  105.  
  106.         FUNCTION Head1Patch(VAR thePatch: TrapPatch;
  107.                             theTrapNum: INTEGER;
  108.                             theRoutine: Ptr): INTEGER;
  109.         { Head1Patch is just like HeadPatch, except that it is intended to patch traps with a single
  110.         long-word parameter. The parameter passed to the trap is also passed to theRoutine.
  111.         theRoutine must be a procedure with one long-word parameter. }
  112.  
  113.         FUNCTION PatchTrap(VAR thePatch: TrapPatch;
  114.                            theTrapNum: INTEGER;
  115.                            theRoutine: Ptr): INTEGER;
  116.         { PatchTrap patches the given trap to theRoutine.  On a 64K ROM machine, we must set up a
  117.         block in the system heap, patch the trap to jump to the block, and insert code in the block
  118.         to jump to theRoutine. }
  119.  
  120.         PROCEDURE SetCallBack(targProc: ProcPtr;
  121.                                  itsRefCon: LONGINT;
  122.                                  theCallBackPtr: CallBackPtr);
  123.         { Prepares a call back record for use.  Stuffs in the target of the call back and the refcon
  124.         to pass as an _additional_ and _last_ parameter to it.  Useful for getting context when being
  125.         called back from the toolBox.  Also useful for avoiding use of globals when getting context }
  126.  
  127.         PROCEDURE UnpatchTrap(VAR thePatch: TrapPatch);
  128.         { UnpatchTrap unpatches the given trap. }
  129.  
  130.         PROCEDURE UnpatchAll;
  131.         { UnpatchAll unpatches all traps. }
  132.         {$ENDC}
  133.  
  134.         {$IFC NOT UsingIncludes}
  135. END.
  136. {$ENDC}
  137.